Skip to content
This repository has been archived by the owner on Feb 20, 2023. It is now read-only.

Automatic docs build #45

Closed
wants to merge 6 commits into from
Closed

Conversation

sechkova
Copy link
Contributor

@sechkova sechkova commented Mar 16, 2022

Fixes #20

Use gh actions to automatically generate the html API docs and add a new commit to the repository on each pull request.

  • Add docs build environment to tox: Use tox to generate the project documentation in an isolated and reproducible environment.
  • Add index.html with redirect: In order to use GitHub pages to automatically generate documentation from docs, an index file is needed in the root dir. However pdoc generates automatically the index file inside the docs/mcat dir. Add docs/index.html with a simple redirect to docs/mcat/index.html.
  • Add docs build to the CI: Add a new gh actions workflow to automatically build the docs and push them to the repository on each push to main.

@sechkova
Copy link
Contributor Author

sechkova commented Mar 16, 2022

Since the automatic build and push of the docs happen on push to main and cannot be seen here, I tested it on my fork and it looks like this: https://github.com/sechkova/ml-conversational-analytic-tool/commits/main Also it needs actual changes to a "*.py" file to be triggered.

This repository could have more restrictions however and the push could fail. Also signing the commit with a GPG key (-S) is not possible by a GH Action as far as I can tell (it is possible by creating a gpg key for this purpose but not in a trivial way).

@sechkova sechkova force-pushed the automatic-docs branch 3 times, most recently from e9f8b9d to d5d3779 Compare March 16, 2022 12:36
@annajung
Copy link
Contributor

just as a reminder, after the PR is merged, we would have to enable github pages for the repo.

I checked the repo setting and we do require signed commits. Could you test out what happens if you enable a signed commit requirement for your forked repo and test out what happens with the workflow there?

@sechkova
Copy link
Contributor Author

sechkova commented Mar 23, 2022

I checked the repo setting and we do require signed commits. Could you test out what happens if you enable a signed commit requirement for your forked repo and test out what happens with the workflow there?

@annajung I guess as expected, the commit is declined.

remote: error: Commits must have valid signatures.

If we want to move forward the idea of an automatic commit, I'll check if it is possible to sign it in a GH Action. I'm not sure who should be the GPG key "owner" though.

Here is the full log:

Run git config --global user.name 'GitHub Actions'
[13](https://github.com/sechkova/ml-conversational-analytic-tool/runs/5662812744?check_suite_focus=true#step:6:13)
[main 5c4d9e3] Build docs
[14](https://github.com/sechkova/ml-conversational-analytic-tool/runs/5662812744?check_suite_focus=true#step:6:14)
 1 file changed, 4 insertions(+), 1 deletion(-)
[16](https://github.com/sechkova/ml-conversational-analytic-tool/runs/5662812744?check_suite_focus=true#step:6:16)
remote: error: GH006: Protected branch update failed for refs/heads/main.        
[17](https://github.com/sechkova/ml-conversational-analytic-tool/runs/5662812744?check_suite_focus=true#step:6:17)
remote: error: Commits must have valid signatures.        
[18](https://github.com/sechkova/ml-conversational-analytic-tool/runs/5662812744?check_suite_focus=true#step:6:18)
To https://github.com/sechkova/ml-conversational-analytic-tool
[19](https://github.com/sechkova/ml-conversational-analytic-tool/runs/5662812744?check_suite_focus=true#step:6:19)
 ! [remote rejected] main -> main (protected branch hook declined)
[20](https://github.com/sechkova/ml-conversational-analytic-tool/runs/5662812744?check_suite_focus=true#step:6:20)
error: failed to push some refs to 'https://github.com/sechkova/ml-conversational-analytic-tool'
[21](https://github.com/sechkova/ml-conversational-analytic-tool/runs/5662812744?check_suite_focus=true#step:6:21)
Error: Process completed with exit code 1.

Use tox to generate the project documentation in an isolated
and reproducible environment.

Signed-off-by: Teodora Sechkova <[email protected]>
In order to use GitHub pages to automatically generate documentation
from docs, an index file is needed in the root dir. However pdoc
generates automatically the index file inside the docs/mcat dir.

Add docs/index.html with a simple redirect to docs/mcat/index.html.

Signed-off-by: Teodora Sechkova <[email protected]>
Add a new gh actions workflow to automatically build
the docs and push them to the repository on each push to main.

Signed-off-by: Teodora Sechkova <[email protected]>
Add a gh action step that checks for uncommitted docs
and fails the CI.

Signed-off-by: Teodora Sechkova <[email protected]>
Modify the trigger condiitons for the tests GH action to run
only on pull requests and pushes to main branch.

Signed-off-by: Teodora Sechkova <[email protected]>
Signed-off-by: Teodora Sechkova <[email protected]>
@sechkova
Copy link
Contributor Author

After checking the potential solututions, trying to surpass the brach protections tules by finding a way for a bot to sign the commits and sharing GPG keys as secrets sounds like an overkill for mcat, and also maybe raises some concerns.

I have this new idea, I modified the workflow to only check for uncommitted changes after building the docs and fail. This way there is a visible mark in the PR of a failure and the PR author can rebuild and commit the docs before merging.

@annajung what do you think?

@annajung
Copy link
Contributor

Closing to clean up for deprecation

@annajung annajung closed this Feb 16, 2023
Sign up for free to subscribe to this conversation on GitHub. Already have an account? Sign in.
Projects
None yet
Development

Successfully merging this pull request may close these issues.

Automate building docs
4 participants